home *** CD-ROM | disk | FTP | other *** search
/ Cream of the Crop 22 / Cream of the Crop 22.iso / bbs / sm103.zip / CGIMAIL.TXT < prev    next >
Text File  |  1996-07-29  |  9KB  |  305 lines
  1. Stalker's CGIMail V1.03      07.29.96 / Eric Voisard
  2. ====================================================
  3.  
  4. Copyright (c) Stalker Lab (SaRL), Switzerland
  5. All Rights Reserved.
  6.  
  7. S T A L K E R  SaRL
  8. Jaquet-Droz 18
  9. 2300 La Chaux-de-Fonds
  10. Switzerland
  11.  
  12. phone: +41 39 225 666
  13. fax: +41 39 225 667
  14. email: tech@cdf.globalcafe.ch (soon: tech@stalker.ch)
  15.  
  16.  
  17. Stalker's CGIMail is freeware and can be freely distributed.
  18. The Software is provided on an "AS IS" basis, without warranty of any
  19. kind. Eric Voisard and Stalker Lab declines any responsability in the
  20. eventuality of damages caused by the use of this software.
  21.  
  22.  
  23.  
  24. 1. INTRODUCTION
  25. ---------------
  26.  
  27. Stalker's CGIMail as says its self-explanatory name, is a CGI program
  28. allowing a http server to send SMTP mail with data coming from a HTML
  29. form.
  30.  
  31. As a 32bits app, it requires Microsoft Windows 95 or (better)
  32. Windows NT. 
  33.  
  34.  
  35.  
  36. 2. FEATURES
  37. -----------
  38.  
  39. The mail is based on template text files with variables in it, and
  40. stored in the server. When launched, Stalker's CGIMail loads a
  41. specified template, replaces the variables with data coming from
  42. HTML form, before to send the resulting text as mail body.
  43.  
  44. Stalker's CGIMail allows multiple "To", "Cc" and "Bcc" recipients, and
  45. is MIME compliant (useful for countries other than US!).
  46.  
  47.  
  48.  
  49. 3. INSTALLATION
  50. ---------------
  51.  
  52. Stalker's CGIMail.exe must be installed in a CGI mapped directory on
  53. the server (not a winCGI one!). CGImail.ini must be in the same
  54. directory. Mail templates may be in other directories.
  55.  
  56.  
  57.  
  58. 4. CALLING THE CGI
  59. ------------------
  60. As a CGI 1.1. specs compliant program, Stalker's CGIMail is called
  61. with the POST method, like:
  62.  
  63. <form method=POST action="/cgi-bin/CGIMail.exe">
  64.  
  65.  
  66.  
  67. 5. VARIABLES
  68. ------------
  69.  
  70. Variables are user defined and Stalker's CGIMail allows up to 1000 of
  71. them. They are words bracketed within '$' chars (e.g. $var$), they can
  72. be up to 32 chars long including '$'s. Variables are case sensitive,
  73. spaces are allowed but their use is discouraged.
  74. The names must be the same in the HTML form and in the templates.
  75. Stalker's CGIMail routine tries to find as many matches as it can
  76. between form names and templates variables, and replaces all what it
  77. can with form values.
  78.  
  79. In example, HTML lines like these:
  80.  
  81. <ol>
  82. <li><input type="radio" name="$var1$" value="I'm born to run UNIX">
  83. I work on UNIX.
  84. <li><input type="radio" name="$var1$" value="NT is a good OS" checked>
  85. I work on NT.
  86. </ol>
  87.  
  88. With a template line like this:
  89.  
  90. Hi, I think $var1$! That's all what I have to say.
  91.  
  92. Will give: 
  93.  
  94. Hi, I think NT is a good OS! That's all what I have to say.
  95.  
  96. Or:
  97.  
  98. Hi, I think I'm born to run UNIX! That's all what I have to say.
  99.  
  100. An unique variable name can be used several times in the template, it
  101. will be replaced as many times as it appears.
  102.  
  103. Note that if a template variable was not passed by form, it is not
  104. treated and is sent "as is" in the mail.
  105. If a form field doesn't have any matches in the template, it is
  106. ignored.
  107.  
  108.  
  109.  
  110. 6. RESERVED VARIABLES
  111. ---------------------
  112.  
  113. Some variables are reserved words for internal use. Some are not
  114. needed, others must be specified in the form. They are:
  115.  
  116. $File$        NEEDED!
  117. Name and pathname of the template to be used with the current form.
  118. (! If no local path is specified, CGImail will check in its directory)
  119.  
  120. $LocationOK$    NEEDED!
  121. The URL to go if mail is correctly sent.
  122. (! If no URL path is specified, CGImail will check in its directory)
  123.  
  124. $LocationKO$    NEEDED!
  125. The URL to go if an error has occured and mail is not sent.
  126. (! If no URL path is specified, CGImail will check in its directory)
  127.  
  128. $Subject$    Not needed
  129. Subject of the mail which appears in the mail header.
  130.  
  131. $Sender$    Not needed
  132. Overrides sender's address of CGImail.ini (see CGImail.ini). 
  133.  
  134. $Realname$    Not needed
  135. Overrides sender's real name of CGImail.ini (see CGImail.ini). 
  136.  
  137. $Optional$    Not needed
  138. For optionally passed values from form (see below).
  139.  
  140. $To$        At least ONE IS NEEDED
  141. A normal "To:" mail recipient.
  142.  
  143. $Cc$        Not needed
  144. A "Carbon-copy" mail recipient.
  145.  
  146. $Bcc$        Not needed
  147. A "Blind Carbon-copy" mail recipient.
  148.  
  149. User can specifie more than one $To$, $Cc$ and $Bcc$ recipients in the
  150. form, but not more than 100 recipients at all.
  151.  
  152. These variables (and others) will not appear on the client's browser
  153. if "hidden" is specified in the HTML form source. 
  154.  
  155.  
  156.  
  157. 7. OPTIONAL VALUES
  158. ------------------
  159.  
  160. Some of the name/value pairs on the form are not necessary passed to
  161. the CGI by the httpd. In example, an unchecked checkbox will neither
  162. send a value, nor its referencing name.
  163. This causes garbage in the resulting message because the CGI does not
  164. find any match for corresponding template variable, and send it "as is"
  165. in the mail.
  166.  
  167. To allow the use of such optional values, the reserved variable
  168. $Optional$ can be specified in the form, with a default value string.
  169. In the template and the form, a prefix "Opt." must be appended in the
  170. concerned variables names (e.g. $Opt.MyCheckBox$).
  171. Then, if the CGI find the $Optional$ reserved variable, it will replace
  172. all remaining $Opt.<name>$ variables with the default value string.
  173. Usually, a NULL string will be used as default string. 
  174.  
  175.  
  176.  
  177. 8. TEMPLATES FILES
  178. ------------------
  179.  
  180. Templates are simple texts that can be edited with the Windows Notepad
  181. in example. Since Stalker's CGIMail is MIME compliant, extended chars
  182. and charsets other than 7 bits US-Ascii can be used.
  183.  
  184. There is no limit with the file size, but each line can't be longer
  185. than 1000 chars and MUST be ended with CR/LF (Carriage-Return and
  186. Line-Feed). Note that UNIX style (LF alone) will work, but Macintosh
  187. type (CR alone) will not.
  188.  
  189. Templates can be stored anywhere in the Web server, but paths (local
  190. paths!) must be specified within the $File$ form variable.
  191.  
  192.  
  193.  
  194. 9. CGIMail.ini
  195. --------------
  196.  
  197. Some setting must be specified in the .ini file:
  198.  
  199. Gateway=
  200. Name of the SMTP relay
  201.  
  202. Sender=
  203. Email address of the sender which will appear in the "From:" field of
  204. the mail header. An idea is to set the webmaster's one, so if the mail
  205. bounces, he is informed.
  206.  
  207. Realname=
  208. Real name of the sender which will also appear in the "From:" field of
  209. the mail header. Can be used to specify that mail comes from a CGI.
  210.  
  211. MIMEncode=
  212. This is a MIME encoding parameter. Stalker's CGIMail uses MIME specs
  213. declarations and encoding.
  214. If MIMEncode=no, mail will be sent 8bits MIME to the mail relay
  215. without encoding.
  216. If MIMEncode=yes, mail will be sent 7bits Quoted-printable MIME
  217. encoded. This setting depends on the mail relay capabilities to handle
  218. 8bits chars, but it is more reliable to force 7bits encoding.
  219.  
  220. Charset=
  221. Specifies the local charset used (e.g. US = us-ascii; Latin =
  222. iso-8859-1)
  223.  
  224.  
  225.  
  226. 10. LOGGING THE PROCESS
  227. ----------------------
  228.  
  229. Each time Stalker's CGIMail is called, it creates or overwrites
  230. CGIMail.log in the CGIMail.exe directory. All the process and the
  231. dialogs with the SMTP gateway are stored in this file. This is useful
  232. for debugging when errors occur or just to verify the process. 
  233.  
  234.  
  235.  
  236. 11. WHEN AN ERROR OCCURS
  237. ------------------------
  238.  
  239. If an error occurs, the client's browser is redirected to $LocationKO$.
  240. When possible, the error is specified in the log file (it's a good
  241. idea to check it, times to times). If the mail message was present
  242. before the error occured, or if the mail was not or partially sent for
  243. any reason, it is appended to the file dead.letter.txt. So it is
  244. possible to handle it manually as a last resort.
  245.  
  246. The only error which can't be logged is the CGI unable to handle the
  247. log file! If the CGI can't open the log file, the process is aborted
  248. and the client receive a brief message asking him to inform the
  249. webmaster.
  250. So, if you never receive mail from the CGI, or if errors seems to
  251. occur but nothing is logged, turn around the log file to fix the
  252. problem.
  253.  
  254.  
  255.  
  256. 12. REFERENCES
  257. --------------
  258.  
  259.  [1] J. Postel,
  260. "SMTP (Simple Mail Transfert Protocol)", RFC 821,  ISI, August 1982
  261.  
  262.  [2] Crocker, D.,
  263. "Standard for the Format of ARPA Internet Text Messages", STD 11,
  264. RFC 822, UDEL, August 1982.
  265.  
  266.  [3] Borenstein N., and N. Freed
  267. "MIME (Multipurpose Internet Mail Extensions)
  268. Part One:  Mechanismsfor Specifying and Describing the Format of
  269. Internet Message Bodies", RFC 1521, Bellcore, Innosoft, September 1993.
  270.  
  271.  [4] K. Moore
  272. "MIME (Multipurpose Internet Mail Extensions)
  273. Part Two: Message Header Extensions for Non-ASCII Text", RFC 1522,
  274. University of Tennessee, September 1993.
  275.  
  276.  [5] D.R.T Robinson
  277. "The WWW Common Gateway Interface Version 1.1", IETF Internet-Draft,
  278. University of Cambridge, 15 February 1996
  279.  
  280.  
  281.  
  282. 13. HISTORY
  283. -----------
  284.  
  285. 07.29.96    Version 1.03
  286. -Added internal variables to override sender's address and real name
  287. of CGImail.ini.
  288. -Added a date stamp on messages appended to dead.letter.txt for better
  289. management.
  290.  
  291. 07.24.96    Version 1.02
  292. -Improved the MIME conversion routine.
  293. -Added optional form values handling.
  294.  
  295.  
  296. 07.10.96    Version 1.01
  297. -Fixed minor bug causing inappropriate error message.
  298. -Changed a test causing the sending (RCPT TO) of recipient list
  299. to be stopped a first incorrect one, and mail to be unsent to
  300. remaining correct recipients. Now, all valid recipients will
  301. receive their mail.
  302.  
  303. 07.02.96    Version 1.00
  304. -First release
  305.